---@meta

--- LuatOS IDE Helper for module: ble
--- ```yaml
--- Summary: 低功耗蓝牙
--- URL: https://gitee.com/openLuat/LuatOS/tree/master/luat/../components/bluetooth/src/luat_lib_ble.c
--- Demo: 
--- Video: 
--- Tag: 
--- ```
--- ```lua
--- 本库用于操作BLE对象, 需要搭配bluetooth.init()使用
--- 详细用法请查阅demo
--- 模式解释
--- 从机模式(peripheral), 设备会被扫描到, 并且可以被连接
--- 主机模式(central), 设备会扫描其他设备, 并且可以连接其他设备
--- 广播者模式(ibeacon), 设备会周期性的广播beacon信息, 但不会被扫描到, 也不会连接其他设备
--- 观察者模式(scan), 设备会扫描其他设备, 但不会连接其他设备
--- 从机模式(peripheral)的基本流程(概要描述)
--- 1. 初始化蓝牙框架
--- 2. 创建BLE对象
--- local ble_device = bluetooth_device:ble(ble_event_cb)
--- 3. 创建GATT描述
--- local att_db = {xxx}
--- 4. 创建广播信息
--- ble_device:adv_create(adv_data)
--- 5. 开始广播
--- ble_device:adv_start()
--- 6. 等待连接
--- 7. 在回调函数中处理连接事件, 如接收数据, 发送数据等
--- 主机模式(central)的基本流程(概要描述)
--- TODO
--- 广播者模式(ibeacon)的基本流程(概要描述)
--- TODO
--- 观察者模式(scan)的基本流程(概要描述)
--- 1. 初始化蓝牙框架
--- 2. 创建BLE对象
--- local ble_device = bluetooth_device:ble(ble_event_cb)
--- 3. 开始扫描
--- ble_device:scan_start()
--- 4. 在回调函数中处理扫描事件, 如接收设备信息等
--- 5. 按需停止扫描
--- ble_device:scan_stop()
--- ```
ble = {}

--- 38 39) (所有通道(37)
ble.CHNLS_ALL = 0

--- 创建一个BLE GATT服务
---@param opts table GATT服务的描述信息
---@return boolean #1 是否创建成功
--- ```lua
--- local att_db = { -- Service
---     string.fromHex("FA00"), -- Service UUID, 服务的UUID, 可以是16位、32位或128位
--- Characteristic
---     { -- Characteristic 1
---         string.fromHex("EA01"), -- Characteristic UUID Value, 特征的UUID值, 可以是16位、32位或128位
---         ble.NOTIFY | ble.READ | ble.WRITE -- Properties, 对应蓝牙特征的属性, 参考权限常量
---         string.fromHex("1234"), -- 默认value
---     }
--- }
--- ble_device:gatt_create(att_db)
--- ```
function ble.gatt_create(opts) end

--- 创建一个BLE广播
---@param opts table 广播的描述信息
---@return boolean #1 是否创建成功
--- ```lua
--- 创建广播信息
--- ble_device:adv_create({
---     addr_mode = ble.PUBLIC, -- 广播地址模式, 可选值: ble.PUBLIC, ble.RANDOM, ble.RPA, ble.NRPA
---     channel_map = ble.CHNLS_ALL, -- 广播的通道, 可选值: ble.CHNLS_37, ble.CHNLS_38, ble.CHNLS_39, ble.CHNLS_ALL
---     intv_min = 120, -- 广播间隔最小值, 单位为0.625ms, 最小值为20, 最大值为10240
---     intv_max = 120, -- 广播间隔最大值, 单位为0.625ms, 最小值为20, 最大值为10240
---     adv_data = { -- 支持表格形式, 也支持字符串形式(255字节以内)
---         {ble.FLAGS, string.char(0x06)},
---         {ble.COMPLETE_LOCAL_NAME, "LuatOS123"}, -- 广播的设备名
---         {ble.SERVICE_DATA, string.fromHex("FE01")}, -- 广播的服务数据
---         {ble.MANUFACTURER_SPECIFIC_DATA, string.fromHex("05F0")}
---     }
--- })
--- ```
function ble.adv_create(opts) end

--- 开始广播
---@return boolean #1 是否成功
--- ```lua
--- 开始广播
--- ble_device:adv_start()
--- 提醒, 对于从机模式, 如果被断开了连接, 则需要重新开始广播, 才能被重新搜索到
--- ```
function ble.adv_start() end

--- 主动停止广播
---@return boolean #1 是否成功
--- ```lua
--- 停止广播
--- ble_device:adv_stop()
--- ```
function ble.adv_stop() end

--- 写入带通知的特征值
---@param opts table 特征值的描述信息
---@param value string value 要写入的值
---@return boolean #1 是否成功
--- ```lua
--- 写入带通知的特征值
--- ble_device:write_notify({
---     uuid_service = "FA00", -- 服务的UUID, 可以是16位、32位或128位
---     uuid_characteristic = "EA01", -- 特征的UUID值, 可以是16位、32位或128位
--- }, "Hello BLE") -- 要写入的值
--- ```
function ble.write_notify(opts, value) end

--- 写入带指示的特征值
---@param opts table 特征值的描述信息
---@param value string value 要写入的值
---@return boolean #1 是否成功
--- ```lua
--- 写入带指示的特征值
--- ble_device:write_indicate({
---     uuid_service = "FA00", -- 服务的UUID, 可以是16位、32位或128位
---     uuid_characteristic = "EA01", -- 特征的UUID值, 可以是16位、32位或128位
--- }, "Hello BLE") -- 要写入的值
--- ```
function ble.write_indicate(opts, value) end

--- 写入特征值
---@param opts table 特征值的描述信息
---@param value string value 要写入的值
---@return boolean #1 是否成功
--- ```lua
--- 写入特征值,填充预设值,被动读取
--- ble_device:write_value({
---     uuid_service = "FA00", -- 服务的UUID, 可以是16位、32位或128位
---     uuid_characteristic = "EA01", -- 特征的UUID值, 可以是16位、32位或128位
--- }, "Hello BLE") -- 要写入的值
--- ```
function ble.write_value(opts, value) end

--- 读取特征值
---@param opts table 特征值的描述信息
---@return boolean #1 是否成功
--- ```lua
--- 读取特征值,通过回调中的 EVENT_READ_VALUE 事件返回读取的value值
--- ble_device:read_value({
---     uuid_service = "FA00", -- 服务的UUID, 可以是16位、32位或128位
---     uuid_characteristic = "EA01", -- 特征的UUID值, 可以是16位、32位或128位
--- })
--- ```
function ble.read_value(opts) end

--- 开关通知监听
---@param opts table 特征值的描述信息
---@param enable boolean enable 开/关 可选,默认开
---@return boolean #1 是否成功
--- ```lua
--- 写入特征值,填充预设值,被动读取
--- ble_device:notify_enable({
---     uuid_service = "FA00", -- 服务的UUID, 可以是16位、32位或128位
---     uuid_characteristic = "EA01", -- 特征的UUID值, 可以是16位、32位或128位
--- }, true) -- 开/关
--- ```
function ble.notify_enable(opts, enable) end

--- 开关指示监听
---@param opts table 特征值的描述信息
---@param enable boolean enable 开/关 可选,默认开
---@return boolean #1 是否成功
--- ```lua
--- 写入特征值,填充预设值,被动读取
--- ble_device:indicate_enable({
---     uuid_service = "FA00", -- 服务的UUID, 可以是16位、32位或128位
---     uuid_characteristic = "EA01", -- 特征的UUID值, 可以是16位、32位或128位
--- }, true) -- 开/关
--- ```
function ble.indicate_enable(opts, enable) end

--- 创建一个BLE扫描
---@param addr_mode number addr_mode 广播地址模式, 可选值: ble.PUBLIC, ble.RANDOM, ble.RPA, ble.NRPA
---@param scan_interval number scan_interval 扫描间隔, 单位为0.625ms, 最小值为20, 最大值为10240
---@param scan_window number scan_window 扫描窗口, 单位为0.625ms, 最小值为20, 最大值为10240
---@return boolean #1 是否创建成功
--- ```lua
--- 创建BLE扫描
--- ble_device:scan_create(ble.PUBLIC, 100, 100)
--- ```
function ble.scan_create(addr_mode, scan_interval, scan_window) end

--- 开始BLE扫描
---@return boolean #1 是否成功
--- ```lua
--- 开始BLE扫描
--- ble_device:scan_start()
--- 提醒, 扫描会一直进行, 直到调用ble.scan_stop()停止扫描
--- 扫描结果会立即执行回调, 同一个设备不会去重, 扫描到数据就会执行回调
--- ```
function ble.scan_start() end

--- 停止BLE扫描
---@return boolean #1 是否成功
--- ```lua
--- 停止BLE扫描
--- ble_device:scan_stop()
--- 提醒, 扫描会一直进行, 直到调用ble.scan_stop()停止扫描
--- ```
function ble.scan_stop() end

--- BLE连接
---@param mac string mac 地址
---@param addr_type number 地址类型 ble.PUBLIC ble.RANDOM
---@return boolean #1 是否成功
--- ```lua
--- BLE连接
--- ble_device:connect(string.fromHex("C8478C4E027D"),0)
--- ```
function ble.connect(mac, addr_type) end

--- BLE断开连接
---@return boolean #1 是否成功
--- ```lua
--- BLE断开连接
--- ble_device:disconnect()
--- ```
function ble.disconnect() end

--- 解码广播数据
---@param data string data 广播数据
---@return table #1 广播数据的解码结果
--- ```lua
--- 解码广播数据
--- local data = string.fromHex("1EFF060001092002BE0F0AAD8A6D2E251ED6DFBB3D15249929E10BE138DF7B")
--- 解析广播数据
--- local adv_data = ble_device:adv_decode(data)
--- if adv_data then
---     for k, v in pairs(adv_data) do
---         log.info("ble", "adv data", v.len, v.tp, v.data:toHex())
---     end
--- end
--- ```
function ble.adv_decode(data) end

--- 获取蓝牙MAC
---@return string #1 当前的MAC
--- ```lua
--- 本函数于2025.8.29新增
--- local mac = ble.mac()
--- log.info("ble mac", mac and mac:toHex())
--- ```
function ble.mac() end
